/*
 * 描          述:  <描述>
 * 修  改   人:  PengQingyang
 * 修改时间:  2022年4月29日
 * <修改描述:>
 */
package com.tx.component.file.context;

import java.io.File;
import java.io.InputStream;
import java.util.List;

import org.springframework.web.multipart.MultipartFile;

import com.tx.component.file.catalog.VitualFileCatalog;
import com.tx.component.file.resource.FCResource;

/**
 * 虚拟资源引擎<br/>
 * <功能详细描述>
 * 
 * @author  PengQingyang
 * @version  [版本号, 2022年4月29日]
 * @see  [相关类/方法]
 * @since  [产品/模块版本]
 */
public interface FileEngine {
    
    /**
     * 获取所有的目录名<br/>
     * <功能详细描述>
     * @return [参数说明]
     * 
     * @return List<String> [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    List<String> getCatalogs();
    
    /**
     * 获取虚拟文件目录操作句柄<br/>
     * <功能详细描述>
     * @param catalog
     * @return [参数说明]
     * 
     * @return VitualFileCatalog [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    VitualFileCatalog getVitualFileCatalog(String catalog);
    
    /**
     * 将目录进行拷贝，用于目录迁移<br/>
     *    下一步提供：虚拟文件目录整体搬迁的逻辑<br/>
     * <功能详细描述>
     * @param sourceCatalog
     * @param targetCatalog [参数说明]
     * 
     * @return void [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    void copy(String sourceCatalog, String targetCatalog);
    
    /**
     * 保存文件<br/>
     * 如果文件已经存在，则复写当前文件<br/>
     * 如果文件不存在，则创建文件后写入<br/>
     * 如果对应文件所在的文件夹不存在，对应文件夹会自动创建<br/>
     *
     * @param vfc VitualFileCatalog
     * @param relativePath 存储路径,此存储路径为文件全路径(包括扩展名)
     * @param input        文件流
     * 
     * @return FileResource 文件定义的实体,以及文件对应访问地址,权限等
     * @throws throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    FCResource save(VitualFileCatalog vfc, String relativePath,
            InputStream input);
    
    /**
     * 保存文件<br/>
     * 如果文件已经存在，则复写当前文件<br/>
     * 如果文件不存在，则创建文件后写入<br/>
     * 如果对应文件所在的文件夹不存在，对应文件夹会自动创建<br/>
     * <功能详细描述>
     * @param vfc
     * @param relativePath
     * @param multipartFile
     * @return [参数说明]
     * 
     * @return FCResource [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    FCResource save(VitualFileCatalog vfc, String relativePath,
            MultipartFile multipartFile);
    
    /**
     * 保存文件<br/>
     * 如果文件已经存在，则复写当前文件<br/>
     * 如果文件不存在，则创建文件后写入<br/>
     * 如果对应文件所在的文件夹不存在，对应文件夹会自动创建<br/>
     * <功能详细描述>
     * @param vfc
     * @param relativePath
     * @param file
     * @return [参数说明]
     * 
     * @return FCResource [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    FCResource save(VitualFileCatalog vfc, String relativePath, File file);
    
    /**
     * 新增文件<br/>
     * <功能详细描述>
     * @param catalog
     * @param relativePath
     * @param input
     * @return [参数说明]
     * 
     * @return FileResource [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    FCResource add(VitualFileCatalog vfc, String relativePath,
            InputStream input);
    
    /**
     * 新增文件<br/>
     * <功能详细描述>
     * @param catalog
     * @param relativePath
     * @param multipartFile
     * @return [参数说明]
     * 
     * @return FileResource [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    FCResource add(VitualFileCatalog vfc, String relativePath,
            MultipartFile multipartFile);
    
    /**
     * 新增文件<br/>
     * <功能详细描述>
     * @param catalog
     * @param relativePath
     * @param file
     * @return [参数说明]
     * 
     * @return FileResource [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    FCResource add(VitualFileCatalog vfc, String relativePath, File file);
    
    /**
     * 根据相对路径删除文件<br/>
     * <功能详细描述>
     * @param catalog
     * @param relativePath
     * @return [参数说明]
     * 
     * @return boolean [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    void delete(VitualFileCatalog vfc, String relativePath);
    
    /**
     * 根据相对路径获取资源<br/>
     * <功能详细描述>
     * @param catalog
     * @param relativePath
     * @return [参数说明]
     * 
     * @return FCResource [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    FCResource find(VitualFileCatalog vfc, String relativePath);
    
    /**
     * 根据相对路径获取资源集合<br/>
     * <功能详细描述>
     * @param catalog
     * @param relativePath
     * @return [参数说明]
     * 
     * @return List<FCResource> [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    List<FCResource> query(VitualFileCatalog vfc, String relativePath);
    
    /**
     * 根据相对路径获取资源集合<br/>
     * <功能详细描述>
     * @param catalog
     * @param relativePath
     * @return [参数说明]
     * 
     * @return List<FCResource> [返回类型说明]
     * @exception throws [异常类型] [异常说明]
     * @see [类、类#方法、类#成员]
     */
    List<FCResource> children(VitualFileCatalog vfc, String relativePath);
    
}
